home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / a_man / cat7 / streamio.z / streamio
Encoding:
Text File  |  2002-10-03  |  39.4 KB  |  788 lines
  1.  
  2.  
  3.  
  4. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      streamio - STREAMS ioctl commands
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttrrrrooooppppttttssss....hhhh>>>>
  13.      iiiinnnntttt iiiiooooccccttttllll ((((ffffiiiillllddddeeeessss,,,, ccccoooommmmmmmmaaaannnndddd,,,, aaaarrrrgggg))))
  14.      iiiinnnntttt ffffiiiillllddddeeeessss,,,, ccccoooommmmmmmmaaaannnndddd;;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      STREAMS [see _i_n_t_r_o(2)] ioctl commands are a subset of _i_o_c_t_l(2) system
  18.      calls which perform a variety of control functions on _s_t_r_e_a_m_s.  The
  19.      arguments _c_o_m_m_a_n_d and _a_r_g are passed to the file designated by _f_i_l_d_e_s and
  20.      are interpreted by the _s_t_r_e_a_m _h_e_a_d.  Certain combinations of these
  21.      arguments may be passed to a module or driver in the _s_t_r_e_a_m.
  22.  
  23.      _f_i_l_d_e_s is an open file descriptor that refers to a _s_t_r_e_a_m.  _c_o_m_m_a_n_d
  24.      determines the control function to be performed as described below.  _a_r_g
  25.      represents additional information that is needed by this command.  The
  26.      type of _a_r_g depends upon the command, but it is generally an integer or a
  27.      pointer to a _c_o_m_m_a_n_d-specific data structure.
  28.  
  29.      Since these STREAMS commands are a subset of _i_o_c_t_l, they are subject to
  30.      the errors described there.  In addition to those errors, the call will
  31.      fail with _e_r_r_n_o set to EINVAL, without processing a control function, if
  32.      the _s_t_r_e_a_m referenced by _f_i_l_d_e_s is linked below a multiplexor, or if
  33.      _c_o_m_m_a_n_d is not a valid value for a _s_t_r_e_a_m.
  34.  
  35.      Also, as described in _i_o_c_t_l, STREAMS modules and drivers can detect
  36.      errors.  In this case, the module or driver sends an error message to the
  37.      _s_t_r_e_a_m _h_e_a_d containing an error value.  This causes subsequent system
  38.      calls to fail with _e_r_r_n_o set to this value.
  39.  
  40.      In previous IRIX releases it was possible to use these operations on
  41.      socket file descriptors by linking with -_l_s_o_c_k_e_t; this is no longer true
  42.      starting with IRIX 6.2.
  43.  
  44. CCCCOOOOMMMMMMMMAAAANNNNDDDD FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  45.      The following _i_o_c_t_l commands, with error values indicated, are applicable
  46.      to all STREAMS files:
  47.  
  48.      I_PUSH       Pushes the module whose name is pointed to by _a_r_g onto the
  49.                   top of the current _s_t_r_e_a_m, just below the _s_t_r_e_a_m _h_e_a_d.  It
  50.                   then calls the open routine of the newly-pushed module.  On
  51.                   failure, _e_r_r_n_o is set to one of the following values:
  52.  
  53.                   [EINVAL]     Invalid module name.
  54.  
  55.                   [EFAULT]     _a_r_g points outside the allocated address space.
  56.  
  57.                   [ENXIO]      Open routine of new module failed.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  71.  
  72.  
  73.  
  74.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  75.  
  76.      I_POP        Removes the module just below the _s_t_r_e_a_m _h_e_a_d of the _s_t_r_e_a_m
  77.                   pointed to by _f_i_l_d_e_s.  _a_r_g should be 0 in an I_POP request.
  78.                   On failure, _e_r_r_n_o is set to one of the following values:
  79.  
  80.                   [EINVAL]     No module present in the _s_t_r_e_a_m.
  81.  
  82.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  83.  
  84.      I_LOOK       Retrieves the name of the module just below the _s_t_r_e_a_m _h_e_a_d
  85.                   of the _s_t_r_e_a_m pointed to by _f_i_l_d_e_s, and places it in a null
  86.                   terminated character string pointed at by _a_r_g.  The buffer
  87.                   pointed to by _a_r_g should be at least FMNAMESZ+1 bytes long.
  88.                   An [#include <sys/conf.h>] declaration is required.  On
  89.                   failure, _e_r_r_n_o is set to one of the following values:
  90.  
  91.                   [EFAULT]     _a_r_g points outside the allocated address space.
  92.  
  93.                   [EINVAL]     No module present in _s_t_r_e_a_m.
  94.  
  95.      I_LIST       Retrieves the entire list of modules between the _s_t_r_e_a_m _h_e_a_d
  96.                   of the _s_t_r_e_a_m pointed to by _f_i_l_d_e_s, and the driver.  If _a_r_g
  97.                   is NULL, then the number of modules is returned.  Otherwise,
  98.                   _a_r_g should point to a _s_t_r_u_c_t _s_t_r__l_i_s_t.  On input, the member
  99.                   _s_l__n_m_o_d_s should be set to the maximum number of module name
  100.                   the caller is ready to accept, and the member _s_l__m_o_d_l_i_s_t
  101.                   should point to an array of _s_t_r_u_c_t _s_t_r__m_l_i_s_t dats structures
  102.                   with at least _s_t_r__n_m_o_d_s elements.  On successful return, the
  103.                   member _s_l__n_m_o_d_s will be updated to reflect the actual number
  104.                   of module names returned.  On failure, _e_r_r_n_o is set to one
  105.                   of the following values:
  106.  
  107.                   [EFAULT]     _a_r_g points outside the allocated address space.
  108.  
  109.                   [EINVAL]     The value of _s_l__n_m_o_d_s is less than or equal to
  110.                                zero.
  111.  
  112.                   [ENOSPC]     The value of _s_l__n_m_o_d_s is less than the actual
  113.                                number of modules.
  114.  
  115.      I_FLUSH      This request flushes all input and/or output queues,
  116.                   depending on the value of _a_r_g.  Legal _a_r_g values are:
  117.  
  118.                   FLUSHR       Flush read queues.
  119.  
  120.                   FLUSHW       Flush write queues.
  121.  
  122.                   FLUSHRW      Flush read and write queues.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  137.  
  138.  
  139.  
  140.                   On failure, _e_r_r_n_o is set to one of the following values:
  141.  
  142.                   [ENOSR]      Unable to allocate buffers for flush message
  143.                                due to insufficient STREAMS memory resources.
  144.  
  145.                   [EINVAL]     Invalid _a_r_g value.
  146.  
  147.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  148.  
  149.      I_SETSIG     Informs the _s_t_r_e_a_m _h_e_a_d that the user wishes the kernel to
  150.                   issue the SIGPOLL signal [see _s_i_g_n_a_l(2) and _s_i_g_s_e_t(2)] when
  151.                   a particular event has occurred on the _s_t_r_e_a_m associated
  152.                   with _f_i_l_d_e_s.  I_SETSIG supports an asynchronous processing
  153.                   capability in STREAMS.  The value of _a_r_g is a bitmask that
  154.                   specifies the events for which the user should be signaled.
  155.                   It is the bitwise-OR of any combination of the following
  156.                   constants:
  157.  
  158.                   S_INPUT      A non-priority message has arrived on a _s_t_r_e_a_m
  159.                                _h_e_a_d read queue, and no other messages existed
  160.                                on that queue before this message was placed
  161.                                there.  This is set even if the message is of
  162.                                zero length.
  163.  
  164.                   S_HIPRI      A priority message is present on the _s_t_r_e_a_m
  165.                                _h_e_a_d read queue.  This is set even if the
  166.                                message is of zero length.
  167.  
  168.                   S_OUTPUT     The write queue just below the _s_t_r_e_a_m _h_e_a_d is
  169.                                no longer full.  This notifies the user that
  170.                                there is room on the queue for sending (or
  171.                                writing) data downstream.
  172.  
  173.                   S_MSG        A STREAMS signal message that contains the
  174.                                SIGPOLL signal has reached the front of the
  175.                                _s_t_r_e_a_m _h_e_a_d read queue.
  176.  
  177.                   A user process may choose to be signaled only of priority
  178.                   messages by setting the _a_r_g bitmask to the value S_HIPRI.
  179.  
  180.                   Processes that wish to receive SIGPOLL signals must
  181.                   explicitly register to receive them using I_SETSIG.  If
  182.                   several processes register to receive this signal for the
  183.                   same event on the same Stream, each process will be signaled
  184.                   when the event occurs.
  185.  
  186.                   If the value of _a_r_g is zero, the calling process will be
  187.                   unregistered and will not receive further SIGPOLL signals.
  188.                   On failure, _e_r_r_n_o is set to one of the following values:
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  203.  
  204.  
  205.  
  206.                   [EINVAL]     _a_r_g value is invalid or _a_r_g is zero and process
  207.                                is not registered to receive the SIGPOLL
  208.                                signal.
  209.  
  210.                   [EAGAIN]     Allocation of a data structure to store the
  211.                                signal request failed.
  212.  
  213.      I_GETSIG     Returns the events for which the calling process is
  214.                   currently registered to be sent a SIGPOLL signal.  The
  215.                   events are returned as a bitmask pointed to by _a_r_g, where
  216.                   the events are those specified in the description of
  217.                   I_SETSIG above.  _a_r_g is assumed to point to an iiiinnnntttt.  On
  218.                   failure, _e_r_r_n_o is set to one of the following values:
  219.  
  220.                   [EINVAL]     Process not registered to receive the SIGPOLL
  221.                                signal.
  222.  
  223.                   [EFAULT]     _a_r_g points outside the allocated address space.
  224.  
  225.      I_FIND       Compares the names of all modules currently present in the
  226.                   _s_t_r_e_a_m to the name pointed to by _a_r_g, and returns 1 if the
  227.                   named module is present in the _s_t_r_e_a_m.  It returns 0 if the
  228.                   named module is not present.  On failure, _e_r_r_n_o is set to
  229.                   one of the following values:
  230.  
  231.                   [EFAULT]     _a_r_g points outside the allocated address space.
  232.  
  233.                   [EINVAL]     _a_r_g does not contain a valid module name.
  234.  
  235.      I_PEEK       Allows a user to retrieve the information in the first
  236.                   message on the _s_t_r_e_a_m _h_e_a_d read queue without taking the
  237.                   message off the queue.  _a_r_g points to a _s_t_r_p_e_e_k structure
  238.                   which contains the following members:
  239.                        struct strbufctlbuf;
  240.                        struct strbufdatabuf;
  241.                        long        flags;
  242.                   The _m_a_x_l_e_n field in the _c_t_l_b_u_f and _d_a_t_a_b_u_f _s_t_r_b_u_f structures
  243.                   [see _g_e_t_m_s_g(2)] must be set to the number of bytes of
  244.                   control information and/or data information, respectively,
  245.                   to retrieve.  If the user sets _f_l_a_g_s to RS_HIPRI, I_PEEK
  246.                   will only look for a priority message on the _s_t_r_e_a_m _h_e_a_d
  247.                   read queue.
  248.  
  249.                   I_PEEK returns 1 if a message was retrieved, and returns 0
  250.                   if no message was found on the _s_t_r_e_a_m _h_e_a_d read queue, or if
  251.                   the RS_HIPRI flag was set in _f_l_a_g_s and a priority message
  252.                   was not present on the _s_t_r_e_a_m _h_e_a_d read queue.  It does not
  253.                   wait for a message to arrive.  On return, _c_t_l_b_u_f specifies
  254.                   information in the control buffer, _d_a_t_a_b_u_f specifies
  255.                   information in the data buffer, and _f_l_a_g_s contains the value
  256.                   0 or RS_HIPRI.  On failure, _e_r_r_n_o is set to the following
  257.  
  258.  
  259.  
  260.                                                                         PPPPaaaaggggeeee 4444
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  268.  
  269.  
  270.  
  271.                   value:
  272.  
  273.                   [EFAULT]     _a_r_g points, or the buffer area specified in
  274.                                _c_t_l_b_u_f or _d_a_t_a_b_u_f is, outside the allocated
  275.                                address space.
  276.  
  277.                   [EBADMSG]    Queued message to be read is not valid for
  278.                                I_PEEK
  279.  
  280.      I_SRDOPT     Sets the read mode using the value of the argument _a_r_g.
  281.                   Legal _a_r_g values are:
  282.  
  283.                   RNORM     Byte-stream mode, the default.
  284.  
  285.                   RMSGD     Message-discard mode.
  286.  
  287.                   RMSGN     Message-nondiscard mode.
  288.  
  289.                   Read modes are described in _r_e_a_d(2).  On failure, _e_r_r_n_o is
  290.                   set to the following value:
  291.  
  292.                   [EINVAL]     _a_r_g is not one of the above legal values.
  293.  
  294.      I_GRDOPT     Returns the current read mode setting in an _i_n_t pointed to
  295.                   by the argument _a_r_g.  Read modes are described in _r_e_a_d(2).
  296.                   On failure, _e_r_r_n_o is set to the following value:
  297.  
  298.                   [EFAULT]     _a_r_g points outside the allocated address space.
  299.  
  300.      I_NREAD      Counts the number of data bytes in data blocks in the first
  301.                   message on the _s_t_r_e_a_m _h_e_a_d read queue, and places this value
  302.                   in the location pointed to by _a_r_g.  _a_r_g is assumed to be a
  303.                   pointer to an iiiinnnntttt.  The return value for the command is the
  304.                   number of messages on the _s_t_r_e_a_m _h_e_a_d read queue.  For
  305.                   example, if zero is returned in _a_r_g, but the _i_o_c_t_l return
  306.                   value is greater than zero, this indicates that a zero-
  307.                   length message is next on the queue.  On failure, _e_r_r_n_o is
  308.                   set to the following value:
  309.  
  310.                   [EFAULT]     _a_r_g points outside the allocated address space.
  311.  
  312.      I_FDINSERT   Creates a message from user specified buffer(s), adds
  313.                   information about another _s_t_r_e_a_m and sends the message
  314.                   downstream.  The message contains a control part and an
  315.                   optional data part.  The data and control parts to be sent
  316.                   are distinguished by placement in separate buffers, as
  317.                   described below.
  318.  
  319.                   _a_r_g points to a _s_t_r_f_d_i_n_s_e_r_t structure which contains the
  320.                   following members:
  321.                        struct strbufctlbuf;
  322.                        struct strbufdatabuf;
  323.  
  324.  
  325.                                                                         PPPPaaaaggggeeee 5555
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  333.  
  334.  
  335.  
  336.                       long         flags;
  337.                        int         fildes;
  338.                        int         offset;
  339.                   The _l_e_n field in the _c_t_l_b_u_f _s_t_r_b_u_f structure [see _p_u_t_m_s_g(2)]
  340.                   must be set to the size of a pointer plus the number of
  341.                   bytes of control information to be sent with the message.
  342.                   _f_i_l_d_e_s in the _s_t_r_f_d_i_n_s_e_r_t structure specifies the file
  343.                   descriptor of the other _s_t_r_e_a_m.  _o_f_f_s_e_t, which must be
  344.                   word-aligned, specifies the number of bytes beyond the
  345.                   beginning of the control buffer where I_FDINSERT will store
  346.                   a pointer.  This pointer will be the address of the read
  347.                   queue structure of the driver for the _s_t_r_e_a_m corresponding
  348.                   to _f_i_l_d_e_s in the _s_t_r_f_d_i_n_s_e_r_t structure.  The _l_e_n field in
  349.                   the _d_a_t_a_b_u_f _s_t_r_b_u_f structure must be set to the number of
  350.                   bytes of data information to be sent with the message or
  351.                   zero if no data part is to be sent.
  352.  
  353.                   _f_l_a_g_s specifies the type of message to be created. A non-
  354.                   priority message is created if _f_l_a_g_s is set to 0, and a
  355.                   priority message is created if _f_l_a_g_s is set to RS_HIPRI.
  356.                   For non-priority messages, I_FDINSERT will block if the
  357.                   _s_t_r_e_a_m write queue is full due to internal flow control
  358.                   conditions.  For priority messages, I_FDINSERT does not
  359.                   block on this condition.  For non-priority messages,
  360.                   I_FDINSERT does not block when the write queue is full and
  361.                   O_NDELAY is set.  Instead, it fails and sets _e_r_r_n_o to
  362.                   EAGAIN.
  363.  
  364.                   I_FDINSERT also blocks, unless prevented by lack of internal
  365.                   resources, waiting for the availability of message blocks in
  366.                   the _s_t_r_e_a_m, regardless of priority or whether O_NDELAY has
  367.                   been specified.  No partial message is sent.  On failure,
  368.                   _e_r_r_n_o is set to one of the following values:
  369.  
  370.                   [EAGAIN]     A non-priority message was specified, the
  371.                                O_NDELAY flag is set, and the  _s_t_r_e_a_m write
  372.                                queue is full due to internal flow control
  373.                                conditions.
  374.  
  375.                   [ENOSR]      Buffers could not be allocated for the message
  376.                                that was to be created due to insufficient
  377.                                STREAMS memory resources.
  378.  
  379.                   [EFAULT]     _a_r_g points, or the buffer area specified in
  380.                                _c_t_l_b_u_f or _d_a_t_a_b_u_f is, outside the allocated
  381.                                address space.
  382.  
  383.                   [EINVAL]     One of the following:  _f_i_l_d_e_s in the
  384.                                _s_t_r_f_d_i_n_s_e_r_t structure is not a valid, open
  385.                                _s_t_r_e_a_m file descriptor; the size of a pointer
  386.                                plus _o_f_f_s_e_t is greater than the _l_e_n field for
  387.                                the buffer specified through _c_t_l_p_t_r; _o_f_f_s_e_t
  388.  
  389.  
  390.                                                                         PPPPaaaaggggeeee 6666
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  398.  
  399.  
  400.  
  401.                                does not specify a properly-aligned location in
  402.                                the data buffer; an undefined value is stored
  403.                                in _f_l_a_g_s.
  404.  
  405.                   [ENXIO]      Hangup received on _f_i_l_d_e_s of the _i_o_c_t_l call or
  406.                                _f_i_l_d_e_s in the _s_t_r_f_d_i_n_s_e_r_t structure.
  407.  
  408.                   [ERANGE]     The _l_e_n field for the buffer specified through
  409.                                _d_a_t_a_b_u_f does not fall within the range
  410.                                specified by the maximum and minimum packet
  411.                                sizes of the topmost _s_t_r_e_a_m module, or the _l_e_n
  412.                                field for the buffer specified through _d_a_t_a_b_u_f
  413.                                is larger than the maximum configured size of
  414.                                the data part of a message, or the _l_e_n field
  415.                                for the buffer specified through _c_t_l_b_u_f is
  416.                                larger than the maximum configured size of the
  417.                                control part of a message.
  418.  
  419.                   I_FDINSERT can also fail if an error message was received by
  420.                   the _s_t_r_e_a_m _h_e_a_d of the _s_t_r_e_a_m corresponding to _f_i_l_d_e_s in the
  421.                   _s_t_r_f_d_i_n_s_e_r_t structure.  In this case, _e_r_r_n_o will be set to
  422.                   the value in the message.
  423.  
  424.      I_STR        Constructs an internal STREAMS ioctl message from the data
  425.                   pointed to by _a_r_g, and sends that message downstream.
  426.  
  427.                   This mechanism is provided to send user _i_o_c_t_l requests to
  428.                   downstream modules and drivers.  It allows information to be
  429.                   sent with the _i_o_c_t_l, and will return to the user any
  430.                   information sent upstream by the downstream recipient.
  431.                   I_STR blocks until the system responds with either a
  432.                   positive or negative acknowledgement message, or until the
  433.                   request "times out" after some period of time.  If the
  434.                   request times out, it fails with _e_r_r_n_o set to ETIME.
  435.  
  436.                   At most, one I_STR can be active on a _s_t_r_e_a_m.  Further I_STR
  437.                   calls will block until the active I_STR completes at the
  438.                   _s_t_r_e_a_m _h_e_a_d.  The default timeout interval for these
  439.                   requests is 15 seconds.  The O_NDELAY [see _o_p_e_n(2)] flag has
  440.                   no effect on this call.
  441.  
  442.                   To send requests downstream, _a_r_g must point to a _s_t_r_i_o_c_t_l
  443.                   structure which contains the following members:
  444.                        int  ic_cmd;   /* downstream command */
  445.                        int  ic_timout;/* ACK/NAK timeout */
  446.                        int  ic_len;   /* length of data arg */
  447.                        char *ic_dp;   /* ptr to data arg */
  448.  
  449.                   _i_c__c_m_d is the internal ioctl command intended for a
  450.                   downstream module or driver and _i_c__t_i_m_o_u_t is the number of
  451.                   seconds (-1 = infinite, 0 = use default, >0 = as specified)
  452.                   an I_STR request will wait for acknowledgement before timing
  453.  
  454.  
  455.                                                                         PPPPaaaaggggeeee 7777
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  463.  
  464.  
  465.  
  466.                   out.  _i_c__l_e_n is the number of bytes in the data argument and
  467.                   _i_c__d_p is a pointer to the data argument.  The _i_c__l_e_n field
  468.                   has two uses:  on input, it contains the length of the data
  469.                   argument passed in, and on return from the command, it
  470.                   contains the number of bytes being returned to the user (the
  471.                   buffer pointed to by _i_c__d_p should be large enough to contain
  472.                   the maximum amount of data that any module or the driver in
  473.                   the _s_t_r_e_a_m can return).
  474.  
  475.                   The _s_t_r_e_a_m _h_e_a_d will convert the information pointed to by
  476.                   the _s_t_r_i_o_c_t_l structure to an internal ioctl command message
  477.                   and send it downstream.  On failure, _e_r_r_n_o is set to one of
  478.                   the following values:
  479.  
  480.                   [ENOSR]      Unable to allocate buffers for the _i_o_c_t_l
  481.                                message due to insufficient STREAMS memory
  482.                                resources.
  483.  
  484.                   [EFAULT]     _a_r_g points, or the buffer area specified by
  485.                                _i_c__d_p and _i_c__l_e_n (separately for data sent and
  486.                                data returned) is, outside the allocated
  487.                                address space.
  488.  
  489.                   [EINVAL]     _i_c__l_e_n is less than 0 or _i_c__l_e_n is larger than
  490.                                the maximum configured size of the data part of
  491.                                a message or _i_c__t_i_m_o_u_t is less than -1.
  492.  
  493.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  494.  
  495.                   [ETIME]      A downstream _i_o_c_t_l timed out before
  496.                                acknowledgement was received.
  497.  
  498.                   An I_STR can also fail while waiting for an acknowledgement
  499.                   if a message indicating an error or a hangup is received at
  500.                   the _s_t_r_e_a_m _h_e_a_d.  In addition, an error code can be returned
  501.                   in the positive or negative acknowledgement message, in the
  502.                   event the ioctl command sent downstream fails.  For these
  503.                   cases, I_STR will fail with _e_r_r_n_o set to the value in the
  504.                   message.
  505.  
  506.      I_SWROPT     Sets the write mode bits using the value of the argument
  507.                   _a_r_g.  Legal bit settings for _a_r_g are:
  508.  
  509.                   SNDZERO      Send a zero-length message downstream when a
  510.                                write of 0 bytes occurs on pipes and FIFOs.
  511.  
  512.                   SNDPIPE      Send SIGPIPE to process if _ssss_dddd______wwww_eeee_rrrr_rrrr_oooo_rrrr is set and
  513.                                the process is doing a write or putmsg.
  514.  
  515.                   SNDHOLD      Activate the STRHOLD feature.
  516.  
  517.  
  518.  
  519.  
  520.  
  521.                                                                         PPPPaaaaggggeeee 8888
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  529.  
  530.  
  531.  
  532.                   On failure, _eeee_rrrr_rrrr_nnnn_oooo may be set to the following value:
  533.  
  534.                   EINVAL       _a_r_g is not a valid value.
  535.  
  536.      I_GWROPT     Returns the current write mode setting, as described above,
  537.                   in the _iiii_nnnn_tttt that is pointed to by the argument _a_r_g.
  538.  
  539.      I_SENDFD     Requests the _s_t_r_e_a_m associated with _f_i_l_d_e_s to send a
  540.                   message, containing a file pointer, to the _s_t_r_e_a_m _h_e_a_d at
  541.                   the other end of a _s_t_r_e_a_m pipe.  The file pointer
  542.                   corresponds to _a_r_g, which must be an integer file
  543.                   descriptor.
  544.  
  545.                   I_SENDFD converts _a_r_g into the corresponding system file
  546.                   pointer.  It allocates a message block and inserts the file
  547.                   pointer in the block.  The user id and group id associated
  548.                   with the sending process are also inserted.  This message is
  549.                   placed directly on the read queue [see _i_n_t_r_o(2)] of the
  550.                   _s_t_r_e_a_m _h_e_a_d at the other end of the _s_t_r_e_a_m pipe to which it
  551.                   is connected.  On failure, _e_r_r_n_o is set to one of the
  552.                   following values:
  553.  
  554.                   [EAGAIN]     The sending _s_t_r_e_a_m is unable to allocate a
  555.                                message block to contain the file pointer.
  556.  
  557.                   [EAGAIN]     The read queue of the receiving _s_t_r_e_a_m _h_e_a_d is
  558.                                full and cannot accept the message sent by
  559.                                I_SENDFD.
  560.  
  561.                   [EBADF]      _a_r_g is not a valid, open file descriptor.
  562.  
  563.                   [EINVAL]     _f_i_l_d_e_s is not connected to a _s_t_r_e_a_m pipe.
  564.  
  565.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  566.  
  567.      I_RECVFD     Retrieves the file descriptor associated with the message
  568.                   sent by an I_SENDFD _i_o_c_t_l over a _s_t_r_e_a_m pipe.  _a_r_g is a
  569.                   pointer to a data buffer large enough to hold an _s_t_r_r_e_c_v_f_d
  570.                   data structure containing the following members:
  571.                        int fd;
  572.                        uid_t uid;
  573.                        gid_t gid;
  574.  
  575.                   _f_d is an integer file descriptor.  _u_i_d and _g_i_d are the user
  576.                   id and group id, respectively, of the sending _s_t_r_e_a_m.
  577.  
  578.                   If O_NDELAY is not set [see _o_p_e_n(2)], I_RECVFD will block
  579.                   until a message is present at the _s_t_r_e_a_m _h_e_a_d.  If O_NDELAY
  580.                   is set, I_RECVFD will fail with _e_r_r_n_o set to EAGAIN if no
  581.                   message is present at the _s_t_r_e_a_m _h_e_a_d.
  582.  
  584.  
  585.  
  586.                                                                         PPPPaaaaggggeeee 9999
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  594.  
  595.  
  596.  
  597.                   If the message at the _s_t_r_e_a_m _h_e_a_d is a message sent by an
  598.                   I_SENDFD, a new user file descriptor is allocated for the
  599.                   file pointer contained in the message.  The new file
  600.                   descriptor is placed in the _f_d field of the _s_t_r_r_e_c_v_f_d
  601.                   structure.  The structure is copied into the user data
  602.                   buffer pointed to by _a_r_g.  On failure, _e_r_r_n_o is set to one
  603.                   of the following values:
  604.  
  605.                   [EAGAIN]     A message was not present at the _s_t_r_e_a_m _h_e_a_d
  606.                                read queue, and the O_NDELAY flag is set.
  607.  
  608.                   [EBADMSG]    The message at the _s_t_r_e_a_m _h_e_a_d read queue was
  609.                                not a message containing a passed file
  610.                                descriptor.
  611.  
  612.                   [EFAULT]     _a_r_g points outside the allocated address space.
  613.  
  614.                   [EMFILE]     NOFILES file descriptors are currently open.
  615.  
  616.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  617.  
  618.      I_SETCLTIME  Sets the stream head close time to the integer value pointed
  619.                   to by _a_r_g.  The stream head close time is the maximum amount
  620.                   of time, in seconds, that the stream head will wait during
  621.                   close for the stream's output queues to empty before calling
  622.                   each module's or driver's close function.  The default value
  623.                   is 15 seconds.  On failure, _e_r_r_n_o is set to one of the
  624.                   following values:
  625.  
  626.                   [EFAULT]     _a_r_g points outside the allocated address space.
  627.  
  628.                   [EINVAL]     _a_r_g points to a value less than 0.
  629.  
  630.      I_GETCLTIME  Returns the current value of the stream head close time
  631.                   (defined above) in the integer pointed to by _a_r_g.  On
  632.                   failure, _e_r_r_n_o is set to one of the following values:
  633.  
  634.                   [EFAULT]     _a_r_g points outside the allocated address space.
  635.  
  636.      The following two commands are used for connecting and disconnecting
  637.      multiplexed STREAMS configurations.
  638.  
  639.      I_LINK       Connects two _s_t_r_e_a_m_s, where _f_i_l_d_e_s is the file descriptor of
  640.                   the _s_t_r_e_a_m connected to the multiplexing driver, and _a_r_g is
  641.                   the file descriptor of the _s_t_r_e_a_m connected to another
  642.                   driver.  The _s_t_r_e_a_m designated by _a_r_g gets connected below
  643.                   the multiplexing driver.  I_LINK requires the multiplexing
  644.                   driver to send an acknowledgement message to the _s_t_r_e_a_m _h_e_a_d
  645.                   regarding the linking operation.  This call returns a
  646.                   multiplexor ID number (an identifier used to disconnect the
  647.                   multiplexor, see I_UNLINK) on success, and a -1 on failure.
  648.                   On failure, _e_r_r_n_o is set to one of the following values:
  649.  
  650.  
  651.  
  652.                                                                        PPPPaaaaggggeeee 11110000
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  660.  
  661.  
  662.  
  663.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  664.  
  665.                   [ETIME]      Time out before acknowledgement message was
  666.                                received at _s_t_r_e_a_m _h_e_a_d.
  667.  
  668.                   [EAGAIN]     Temporarily unable to allocate storage to
  669.                                perform the I_LINK.
  670.  
  671.                   [ENOSR]      Unable to allocate storage to perform the
  672.                                I_LINK due to insufficient STREAMS memory
  673.                                resources.
  674.  
  675.                   [EBADF]      _a_r_g is not a valid, open file descriptor.
  676.  
  677.                   [EINVAL]     _f_i_l_d_e_s _s_t_r_e_a_m does not support multiplexing.
  678.  
  679.                   [EINVAL]     _a_r_g is not a _s_t_r_e_a_m, or is already linked under
  680.                                a multiplexor.
  681.  
  682.                   [EINVAL]     The specified link operation would cause a
  683.                                "cycle" in the resulting configuration; that
  684.                                is, if a given _s_t_r_e_a_m _h_e_a_d is linked into a
  685.                                multiplexing configuration in more than one
  686.                                place.
  687.  
  688.                   An I_LINK can also fail while waiting for the multiplexing
  689.                   driver to acknowledge the link request, if a message
  690.                   indicating an error or a hangup is received at the _s_t_r_e_a_m
  691.                   _h_e_a_d of _f_i_l_d_e_s.  In addition, an error code can be returned
  692.                   in the positive or negative acknowledgement message.  For
  693.                   these cases, I_LINK will fail with _e_r_r_n_o set to the value in
  694.                   the message.
  695.  
  696.      I_UNLINK     Disconnects the two _s_t_r_e_a_m_s specified by _f_i_l_d_e_s and _a_r_g.
  697.                   _f_i_l_d_e_s is the file descriptor of the _s_t_r_e_a_m connected to the
  698.                   multiplexing driver.  _f_i_l_d_e_s must correspond to the _s_t_r_e_a_m
  699.                   on which the _i_o_c_t_l I_LINK command was issued to link the
  700.                   _s_t_r_e_a_m below the multiplexing driver.  _a_r_g is the
  701.                   multiplexor ID number that was returned by the I_LINK.  If
  702.                   _a_r_g is -1, then all Streams which were linked to _f_i_l_d_e_s are
  703.                   disconnected.  As in I_LINK, this command requires the
  704.                   multiplexing driver to acknowledge the unlink.  On failure,
  705.                   _e_r_r_n_o is set to one of the following values:
  706.  
  707.                   [ENXIO]      Hangup received on _f_i_l_d_e_s.
  708.  
  709.                   [ETIME]      Time out before acknowledgement message was
  710.                                received at _s_t_r_e_a_m _h_e_a_d.
  711.  
  712.                   [ENOSR]      Unable to allocate storage to perform the
  713.                                I_UNLINK due to insufficient STREAMS memory
  714.                                resources.
  715.  
  716.  
  717.  
  718.                                                                        PPPPaaaaggggeeee 11111111
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725. SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))                                                        SSSSTTTTRRRREEEEAAAAMMMMIIIIOOOO((((7777))))
  726.  
  727.  
  728.  
  729.                   [EINVAL]     _a_r_g is an invalid multiplexor ID number or
  730.                                _f_i_l_d_e_s is not the _s_t_r_e_a_m on which the I_LINK
  731.                                that returned _a_r_g was performed.
  732.  
  733.                   An I_UNLINK can also fail while waiting for the multiplexing
  734.                   driver to acknowledge the link request, if a message
  735.                   indicating an error or a hangup is received at the _s_t_r_e_a_m
  736.                   _h_e_a_d of _f_i_l_d_e_s.  In addition, an error code can be returned
  737.                   in the positive or negative acknowledgement message.  For
  738.                   these cases, I_UNLINK will fail with _e_r_r_n_o set to the value
  739.                   in the message.
  740.  
  741.      FIONREAD     Counts the number of data bytes in data blocks in the first
  742.                   message on the _s_t_r_e_a_m _h_e_a_d read queue, and places this value
  743.                   in the location pointed to by _a_r_g.  _a_r_g is assumed to be a
  744.                   pointer to an iiiinnnntttt.
  745.  
  746.      FIORDCHK     Counts the number of data bytes in data blocks in the first
  747.                   message on the _s_t_r_e_a_m _h_e_a_d read queue, and returns this
  748.                   value.
  749.  
  750.      FIONBIO      Enables or disables non-blocking mode, according to the
  751.                   boolean value of the contents of _a_r_g.  _a_r_g is a pointer to
  752.                   an _i_n_t.  Enabling this mode has the same effect as the
  753.                   OOOO____NNNNDDDDEEEELLLLAAAAYYYY flag for _o_p_e_n(2).
  754.  
  755. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  756.      close(2), fcntl(2), intro(2), ioctl(2), open(2), read(2), getmsg(2),
  757.      poll(2), putmsg(2), signal(2), sigset(2), write(2), termio(7)
  758.  
  759. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  760.      Unless specified otherwise above, the return value from _i_o_c_t_l is 0 upon
  761.      success and -1 upon failure with _e_r_r_n_o set as indicated.
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.                                                                        PPPPaaaaggggeeee 11112222
  785.  
  786.  
  787.  
  788.